.TH lha_app_probes 1 "31 March 2010" "TrueCL Commands"

.SH NAME
lha_app_probes \- Allows the management of custom application probes

.SH SYNOPSES
.TS
l l.
lha_app_probe	\fB--set\fP    \fB--application\fP \fIA\fP \fB--file\fP \fIF\fP [\fB--force\fP]
lha_app_probe	\fB--get\fP    \fB--application\fP \fIA\fP \fB--file\fP \fIF\fP [\fB--force\fP]
lha_app_probe	\fB--delete\fP \fB--application\fP \fIA\fP \fB--file\fP \fIF\fP [\fB--force\fP]
lha_app_probe	\fB--list\fP
.TE

.SH DESCRIPTION
The \fIlha_app_probes(1)\fP command is used to retrieve, set or remove custom
application probes for applications running under TrueCL. A custom application
probe is a script which can be executed by TrueCL (as "root") on each node to 
ascertain whether the application is currenty running on the local node.

Many applications do not need such probles since the standard probing performed
by TrueCL is often good enough. Even without custom probes, TrueCL will use the
following mechanisms for determining whether a particular node is currently
hosting an application.

.TP 4
.B *
If one of more of the application IP addresses defined appears to be
configured on the node.
.TP
.B *
Whether one or more of the volume groups or file systems configured
appear to be available/mounted on the node.
.RE

Sometimes this is not enough - for example if an application has no
storage or IP addresses defined and instead just uses a series of 
processes - that might be a good example for a custom probe.

.SS Example Custom Probe
The application probe is extract from the database, saved to a file, made
executable and then executed. Hence it is typically a shell script or
a script in another language (Python or Perl being common).

The script is expected to take two arguments: application name and action.

The action will be either of:

.TP 10
.B validate
This might perform actinos to ensure the script is working as expected.
It should print "OK" or a failure message to standard output.
.TP
.B test
When this argument is received the script should perform any activities
locally to determine whether the application is running, and if it is then
it should print "UP" on standard output, or "DOWN" if not.
.RE

A sample script might look like the following:

.TS
l.
#!/usr/bin/ksh

app=$1
action=$2

[[ -z "$app" || -z "$action" ]] && {
   print -u2 "ERROR: Invalid usage";
   exit 1;
}

[[ $action = "validate" ]] && {
   print "OK";
   exit 0;
}

if [[ $action = "test" ]]
then
   c=$(ps -ef | grep /my/app/name | wc -l)
   [[ $c -gt 3 ]] && {
      print "UP";
   } || {
      print "DOWN";
   }
fi

exit 0

.TE
.SH ARGUMENTS
.TP 8
--get
This is used to retrieve the existing application probe script. If none
is presently defined for the application an error will be given.
.TP
--set
Create or update the application probe based on the contents of the
specified file.
.TP
--list
Simply produce a list of applications in the cluster which currently
have a custom application probe script defined, and also indicate
the date/time this was added or updated.
.TP
--delete
Delete the custom application probe for the application in question if
one exists.
.TP
--application
The name of the application for which to perform the specified action.
The application does not need to be validated as yet.
.TP
--file
The name of the file. This must be writable and not exist if the
action is \fB--get\fP, and must exist and be readable if the action is
\fB--set\fP. The argument is ignored if the \fB--delete\fP option is used
instead.
.TP
--verbose
Produce progress messages when appropriate.
.TP
--quiet
Only show warnings and errors.
.TP
--silent
Only show fatal errors.
.TP
--lwidth
Alter the line output width from the default of 80 (or the terminal
width if it can be determined).

.SH EXIT CODES
If the action complete successfully '0' will be returned, otherwise
any othe value indicates a fatal error.

.SH FILES
The contents of the custom application probe is stored in the 
TrueCL configuration database - \fB$TRUECL_CFG/config.db\fP.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2010, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR lha_query(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

